TextInput

TextInput is an editable text field component used to capture textual user input. Similar to the Label, this component is merely a wrapper for a standard textField, and therefore supports the same capabilities of the textField such as password mode, maximum number of characters and HTML text. Only a handful of these properties are exposed by the component itself, while the rest can be modified by directly accessing the TextInput’s textField instance.

The TextInput component should be used for input, since noneditable text can be displayed using the Label. Similar to the Label, developers may substitute standard textFields for TextInput components based on their requirements. However, when developing sophisticated UIs, especially for PC applications, the TextInput component provides valuable extended capabilities over the standard textField.

For starters, TextInput supports the focused and disabled state, which are not easily achieved with the standard textField. Due to the separated focus state, TextInput can support custom focus indicators, which are not included with the standard textField. Complex AS2 code is required to change the visual style of a standard textField, while the TextInput visual style can be configured easily on the timeline. The TextInput inspectable properties provide an easy workflow for designers and programmers who are not familiar with Flash Studio. Developers can also easily listen for events fired by the TextInput to create custom behaviors.

The TextInput also supports the standard selection and cut, copy, and paste functionality provided by the textField, including multi paragraph HTML formatted text. By default, the keyboard commands are select (Shift+Arrows), cut (Shift+Delete), copy (Ctrl+Insert), and paste (Shift+Insert).


Inspectable Properties
The inspectable properties of the TextInput component are:

• text: Sets the text of the textField.
• visible: Hides the component if set to false.
• disabled: Disables the component if set to true.
• editable: Makes the TextInput non-editable if set to false.
• maxChars: A number greater than zero limits the number of characters that can be entered in the textField.
• password: If true, sets the textField to display '*' characters instead of the real characters. The value of the textField will be the real characters entered by the user – returned by the text property.
• defaultText: Text to display when the textField is empty. This text is formatted by the defaultTextFormat object, which is by default set to light gray and italics.
• actAsButton: If true, then the TextInput will behave similar to a Button when not focused and support rollOver and rollOut states. Once focused via mouse press or tab, the TextInput reverts to its normal mode until focus is lost.
• enableInitCallback: If set to true, _global.CLIK_loadCallback() will be fired when a component is loaded and _global.CLIK_unloadCallback will be called when the component is unloaded. These methods receive the instance name, target path, and a reference the component as parameters. _global.CLIK_loadCallback and _global.CLIK_unloadCallback should be overriden from the game engine using GFx FunctionObjects.
• soundMap: Mapping between events and sound process. When an event is fired, the associated sound process will be fired via _global.gfxProcessSound, which should be overriden from the game engine using GFx FunctionObjects.

States
The CLIK TextInput component supports three states based on its focused and disabled properties.

• default or enabled state.
• focused state, typically a represented by a highlighted border around the textField.
• disabled state.

Events
All event callbacks receive a single Object parameter that contains relevant information about the event. The following properties are common to all events.

• type: The event type.
• target: The target that generated the event.

The events generated by the TextInput component are listed below. The properties listed next to the event are provided in addition to the common properties.

• show: The component’s visible property has been set to true at runtime.
• hide: The component’s visible property has been set to false at runtime.
• focusIn: The component has received focus.
• focusOut: The component has lost focus.
• textChange: The text field contents have changed.
• rollOver: The mouse cursor has rolled over the component when not focused. Only fired when the actAsButton property is set.
  • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
• rollOut: The mouse cursor has rolled out of the component when not focused. Only fired when the actAsButton property is set.
  • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.